home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d18 / totdoc.arc / CHAPT17.TXT < prev    next >
Text File  |  1991-02-10  |  15KB  |  301 lines
  1.                                                                        Replacing
  2.                                                                              the
  3.                                                                           Screen
  4.                                                                           Writer
  5.  
  6.          "I don't want to achieve immortality through my work, I want to achieve
  7.          immortality by not dying."
  8.  
  9.                                                                      Woody Allen
  10.  
  11.  
  12.          The Toolkit uses some assembly language routines for writing to the
  13.          screen, as well as for moving blocks of data to and from the screen.
  14.          The routines are optimized for maximum speed, and by-pass BIOS, i.e.
  15.          they write directly to the video area of memory. If you are using a
  16.          non-standard display device, such as a palmtop computer, or you don't
  17.          like the (1..80,1..25) coordinate scheme, or for whatever other reason,
  18.          you can develop your own screen writing code to meet your custom needs.
  19.          In this chapter you will learn how to create an object to replace the
  20.          Toolkit's screen writing routines.
  21.  
  22.  
  23. Understanding ScreenOBJ and WriteOBJ
  24.  
  25.          Before discussing how to replace the Toolkit's methods, you need to
  26.          understand how those methods work. Bear in mind that your replacement
  27.          algorithms may need to write to virtual screens as well as to the
  28.          physical screen.
  29.          The ScreenOBJ object is the primary Toolkit object for managing screen
  30.          and video related activity. The global instance Screen is automatically
  31.          initialized when you use the totFAST unit, and you should use the
  32.          Screen instance for all writing to the visible display. Additional
  33.          ScreenOBJ instances can be used to manage virtual (or non-visible)
  34.          screens. The method SAVE is used to save a copy of the visible screen,
  35.          and the method CREATE is used to create an empty virtual screen with
  36.          maximum dimensions of 255 rows by 255 columns. All or part of a virtual
  37.          screen can subsequently be displayed on the visible screen.
  38.  
  39.          Each ScreenOBJ instance includes a pointer to a WriteOBJ object. Wri-
  40.          teOBJ actually performs the core screen writing functions. For example,
  41.          when you call ScreenOBJ's method WriteAT, behind the scenes the Toolkit
  42.          calls the WriteOBJ method WriteAT. By instructing ScreenOBJ to point to
  43.          a different WriteOBJ object you can change how screen tasks are per-
  44.          formed. In other words, by creating a new WriteOBJ object, you change
  45.          how the Toolkit accesses the video functions.
  46.          The two step process is to create a descendant of WriteOBJ, and then
  47.          instruct all ScreenOBJ instances to use this new object.
  48.  
  49.  
  50.  
  51. 17-2                                                       Extending the Toolkit
  52. --------------------------------------------------------------------------------
  53.  
  54. Replacing WriteOBJ
  55.  
  56.          The primary functions of WriteOBJ are to write to the screen, to move
  57.          blocks of data to and from the screen, to position the cursor, to
  58.          manage window settings, and to change the display attribute of a rect-
  59.          angular area of the screen.
  60.          The declaration of WriteOBJ is as follows:
  61.  
  62.          WritePtr = ^WriteOBJ;
  63.          WriteOBJ = object
  64.             vWidth: byte;           {how wide is screen}
  65.             vScreenPtr: pointer;    {memory location of screen data}
  66.             vWindow: tByteCoords;   {active screen area}
  67.             vWindowOn: boolean;     {is window area active}
  68.             vWindowIgnore: boolean; {ignore window settings}
  69.             {methods...}
  70.             Constructor Init;
  71.             procedure   SetScreen(var P:Pointer; W:byte);
  72.             function    WindowOff: boolean;
  73.             procedure   SetWinIgnore(On:Boolean);
  74.             procedure   WindowOn;
  75.             procedure   WindowCoords(var Coords: tByteCoords);
  76.             function    WindowActive: boolean;
  77.             function    WinX: byte;
  78.             function    WinY: byte;
  79.             procedure   GetWinCoords(var X1,Y1,X2,Y2:byte);
  80.             procedure   WriteAT(X,Y,attr:byte;Str:string);             VIRTUAL;
  81.             procedure   WritePlain(X,Y:byte;Str:string);               VIRTUAL;
  82.             procedure   Write(Str:string);                             VIRTUAL;
  83.             procedure   WriteLn(Str:string);                           VIRTUAL;
  84.             procedure   GotoXY(X,Y: word);                             VIRTUAL;
  85.             function    WhereX: word;                                  VIRTUAL;
  86.             function    WhereY: word;                                  VIRTUAL;
  87.             procedure   SetWindow(X1,Y1,X2,Y2: byte);                  VIRTUAL;
  88.             procedure   ResetWindow;                                   VIRTUAL;
  89.             procedure   ChangeAttr(Col,Row,Att:byte;Len:word);         VIRTUAL;
  90.             procedure   MoveFromScreen(var Source,Dest;Length:Word);   VIRTUAL;
  91.             procedure   MoveToScreen(var Source,Dest; Length:Word);    VIRTUAL;
  92.             procedure   Clear(Att:byte;Ch:char);                       VIRTUAL;
  93.             destructor  Done;                                          VIRTUAL;
  94.          end; {WriteOBJ}
  95.  
  96.          WriteOBJ's data describes the size and memory location of the screen,
  97.          and the status of the window settings.
  98.  
  99.  
  100.  
  101. Replacing the Screen Writer                                                 17-3
  102. --------------------------------------------------------------------------------
  103.  
  104.          vWidth is a byte variable which identifies the width of the screen.
  105.          vScreenPtr is a pointer to the start of the screen display memory area.
  106.          The memory is organized into byte pairs, like actual video display
  107.          memory - the first byte is the attribute of a character and the second
  108.          byte is the ASCII code of the character. The associated ScreenOBJ
  109.          instance allocates the necessary memory and calls the WriteOBJ method
  110.          SetScreen to update the vWidth and vScreenPtr variables.
  111.  
  112.          The other variables provide information about the screen's active win-
  113.          dow. vWindow is a record describing the (X1,Y1) and (X2,Y2) active
  114.          window coordinates. vWindowOn and vWindowIgnore are two boolean
  115.          variables which indicate whether the window settings are active. If
  116.          vWindowOn is false or vWindowIgnore is true, the WriteOBJ screen writ-
  117.          ing methods should ignore the current window settings.
  118.          The virtual methods shown in the WriteOBJ declaration represent the
  119.          heart of the screen writing routines. The table below describes their
  120.          specific purpose.
  121.  
  122.  
  123.                         Method                           Description
  124.  
  125.           WriteAT(X,Y,attr:byte;Str:string);  Writes to the screen at (X,Y)
  126.                                               using the specified attribute.
  127.           WritePlain(X,Y:byte;Str:string);    Writes to the screen at (X,Y)
  128.                                               using that region's attribute.
  129.           Write(Str:string);                  Writes at the current cursor
  130.                                               position like Turbo's Write.
  131.           WriteLn(Str:string);                Write at the current cursor posi-
  132.                                               tion like Turbo's WriteLn.
  133.           GotoXY(X,Y: word);                  Positions the cursor at (X,Y).
  134.  
  135.           WhereX: word;                       Returns the cursor's X coordi-
  136.                                               nate.
  137.           WhereY: word;
  138.                                               Returns the cursor's Y coordi-
  139.           SetWindow(X1,Y1,X2,Y2: byte);       nate.
  140.  
  141.           ResetWindow;                        Sets the window coordinates to
  142.                                               specified coordinates.
  143.           ChangeAttr(Col,Row,Att:byte;        Sets the window coordinates to
  144.                      Len:word);               entire screen.
  145.           MoveFromScreen(var Source,Dest;     Changes the display attribute to
  146.                              Len:Word);       Att starting at (X,Y) for Len
  147.                                               bytes.
  148.                                               Moves a block of memory from
  149.           MoveToScreen(var Source,Dest;       Source to Dest, assuming Source
  150.                            Len:Word);         is the visible screen. Len repre-
  151.           Clear(Att:byte;Ch:char);            sents the number of words (not
  152.  
  153.  
  154.  
  155. 17-4                                                       Extending the Toolkit
  156. --------------------------------------------------------------------------------
  157.  
  158.                                               bytes) to move.
  159.                                               As above, but assumes Dest is the
  160.           Done;                               visible screen.
  161.                                               Clears a rectangular area of the
  162.                                               display to the specified attrib-
  163.                                               ute and replaces all characters
  164.                                               with Ch.
  165.                                               Disposes of the object.
  166.  
  167.  
  168.          To develop your own WriteOBJ object, you should create a descendant of
  169.          WriteOBJ, and thanks to inheritance, you can replace as little as one
  170.          procedure or as many as all of them.
  171.          The file EXTSCR1.PAS is a demonstration unit which creates a new
  172.          object. The new object is called MonoWriteOBJ, and the objective is to
  173.          force the Toolkit to use the attribute white-on-black, regardless of
  174.          the attribute specified. The declaration of MonoWriteOBJ is as follows:
  175.  
  176.          Unit ExtFast;
  177.          {$I TOTFLAGS.INC}
  178.          INTERFACE
  179.          uses DOS, CRT, totFAST;
  180.  
  181.          TYPE
  182.          MonoWriteOBJ = object (WriteOBJ)
  183.             constructor Init;
  184.             procedure   WriteAT(X,Y,attr:byte;Str:string);       VIRTUAL;
  185.             procedure   ChangeAttr(X,Y,Att:byte;Len:word);       VIRTUAL;
  186.             procedure   Clear(Att:byte;Ch:char);                 VIRTUAL;
  187.             destructor  Done;                                    VIRTUAL;
  188.          end; {MonoWriteOBJ}
  189.  
  190.          IMPLEMENTATION
  191.          constructor MonoWriteOBJ.Init;
  192.          {}
  193.          begin
  194.             WriteOBJ.Init;
  195.             TextColor(white);
  196.             Textbackground(black);
  197.          end; {MonoWriteOBJ.Init}
  198.  
  199.          procedure MonoWriteOBJ.WriteAT(X,Y,attr:byte;Str:string);
  200.          {}
  201.          begin
  202.             WriteOBJ.WriteAT(X,Y,white,Str);
  203.          end; {MonoWriteOBJ.WriteAT}
  204.  
  205.  
  206.  
  207.  
  208. Replacing the Screen Writer                                                 17-5
  209. --------------------------------------------------------------------------------
  210.  
  211.          procedure MonoWriteOBJ.ChangeAttr(X,Y,Att:byte;Len:word);
  212.          {}
  213.          begin
  214.             WriteOBJ.ChangeAttr(X,Y,white,Len);
  215.          end; {MonoWriteOBJ.ChangeAttr}
  216.  
  217.          procedure MonoWriteOBJ.Clear(Att:byte;Ch:char);
  218.          {}
  219.          begin
  220.             WriteOBJ.Clear(white,Ch);
  221.          end; {MonoWriteOBJ.Clear}
  222.          destructor MonoWriteOBJ.Done;
  223.          {}
  224.          begin
  225.             WriteOBJ.Done;
  226.          end; {MonoWriteOBJ.Done}
  227.  
  228.          end.
  229.  
  230.          MonoWriteOBJ redefines the three primary methods which control display
  231.          attributes. It intercepts the requested attribute and always substi-
  232.          tutes the attribute white.
  233.  
  234.          If you want to modify the way the Toolkit writes to the physical
  235.          screen, but are satisfied with the virtual screen routines, then your
  236.          unit should use the totSYS unit, and the revised methods should use the
  237.          following statement to determine whether the instance is pointing to
  238.          the visible screen:
  239.          if vScreenPtr = Monitor^.BaseOfScreen then
  240.             {new visible screen routines}
  241.          else {virtual screen}
  242.             {call equivalent WriteOBJ method};
  243.  
  244.  
  245.  
  246. Using the Method AssignWriteOBJ
  247.          Having created your new object, you must instruct the Toolkit to use
  248.          it. This is achieved by initializing your object, and then calling the
  249.          ScreenOBJ method AssignWriteOBJ method. For example:
  250.  
  251.                   Screen.AssignWriteOBJ(WhiteWrite);
  252.          Any virtual screens you create must be assigned the new WriteOBJ object
  253.          individually in the same manner. For example:
  254.  
  255.                   Save3.AssignWriteOBJ(WhiteWrite);
  256.  
  257.  
  258.  
  259.  
  260. 17-6                                                       Extending the Toolkit
  261. --------------------------------------------------------------------------------
  262.  
  263.          The demo program, EXTDEM3.PAS, listed below, shows the new ExtFast unit
  264.          in use. This program is actually an adaptation of DEMBR1, which uses
  265.          MonoWriteOBJ in preference to WriteOBJ. If you run it, you will see
  266.          that the entire display uses white on black, even though other attrib-
  267.          utes are specified.
  268.  
  269.  
  270.          Program ExtendedDemoThree;
  271.          {EXTDEM3 - this program shows how to use the MonoWriteOBJ object
  272.           developed in the ExtFast unit. The demo is actually a simple
  273.           adaptation of the browse demo file DEMBR1}
  274.  
  275.          Uses DOS,CRT,
  276.               totINPUT, totFAST,totLIST, totSTR, ExtFast;
  277.          var
  278.             WhiteWrite: MonoWriteOBJ;
  279.             BWin: BrowseArrayOBJ;
  280.             StringList: array[1..26] of string[100];
  281.             I : integer;
  282.  
  283.          begin
  284.             WhiteWrite.Init;
  285.             Screen.AssignWriteOBJ(WhiteWrite);
  286.             for I := 1 to 26 do  {first assign something to the string array}
  287.                StringList[I] := 'Line '+IntToStr(I)+': '+replica-
  288.          te(80,char(I+64));
  289.             ShadowTot^.SetShadowStyle(downright,red,chr(219));
  290.             Screen.Clear(green,' '); {paint the screen}
  291.             Key.SetFast;
  292.             Key.SetClick(true);
  293.             with BWin do
  294.             begin
  295.                Init;
  296.                AssignList(StringList,26,100);
  297.                Go;
  298.                Done;
  299.             end;
  300.          end.
  301.